vim: linebreak

##Description of program and its development


  myo gesture [in0]     -> replay 
                                  -> zipper -> send command to drone [out]
  myo orientation [in1] -> replay 

[f1] diagram of the stream graph

Myoar serves as plumming between the Myo Armband and the AR Drone (v2). It listens on Myo's events, interprets them, and issues appropriate commands to AR Drone. The program takes the shape of a stream, where the flow of Myo events is processed into commands for the drone, and then directed to a sink, which executes those commands given a connected-to drone. Figure 1 (f1) illustrates the shape of the stream. The choice of the stream reactive paradigm allows for high throughput processing, immutable datastructures and overall idiomatic program design. 

Conceptually, Myo is a natural controller for the drone, because it captures orientation data, while the drone takes declarative commands parametrized with orientation (from here on -- wanted orientation or wanted state). I.e. the drone's orientation can be controlled by rotating the Myo. Below follow small quirks encountered when connecting these devices.
  - The control scheme chosen is one which uses gestures in addition to orientation data. These different types of events are emitted separately by the drone; therefore they have to be somehow joined to interpret Myo's current state into commands.
    - This is solved, by having two inlets into the stream, which in the event of downstream demand replay the last received event. Then the two substreams are zipped into a single stream. The zipping process is also the interpretation, so it emits commands for the drone. Because the events can be replayed if necessary, even if different event types arrive at different speeds, the faster ones can be zipped with the last received event of the slower type, without waiting for a new one to arrive. This effectively assures zipping of latest myo data, without use of mutable variables.
  - Myo uses quarternions to represent 3d rotation, but the drone takes three scalars, one for each dimension, in range -1 to 1. Conversion has to be made.
    - Multiple open source libraries contain quarternion helpers that can convert it to radian rotation, which can then be compressed to needed range. NASA's WorldWind is used on a trial basis purely because of NASA's positive reputation.
    - MyoPilot's source code is used as reference.
  - The drone control scheme also relies on change in events. Specifically, change of gesture. This means the stream has to track the last gesture. 
    - Ideally, the stream paradigm would be used, i.e. state would be captured in a graph loop. However, instead, thread-safe mutable variables were used, because of simpler implementation. Performance implications of using mutable locking variables are possibly not significant, because the stream is synchronious, processing events serially; therefore, locking should have little effect.
  - The drone proved to be too sensitive to linear Myo's input.
    - Myo's signal was cubed, following the example of MyoPilot, to reduce the sensitivity, while preserving range of possible rotation.

##Reactive stream processing compared to callbacks

Reactive stream processing (RSP) allows for thread-safe, synchronious, asynchronious and concurrent data flow processing. The Reactive Streams specification and compliant libraries, like the one used, allows for backpressure, which can be used to assure that slow consumers are not overwhelmed by faster producers. The stream graph is composed of modules and can take shapes of arbitrary complexity. 

A stream can be compared to a function taking inputs and responding with outputs. The stream paradigm has the critical advantage of being aware of the data flow. This has multiple practical implications.
  - Back pressure can be applied in case of a slower consumer. Proper handling of back pressure assures that the stream does not overflow. It is implemented by having downstream signal demand upstream. This differs from a pull based stream, which is not performant when downstream is faster, in that downstream can signal demand in advance, and signalling is asynchronious.
  - In case of back pressure, produced elements may be handled in various ways. They may be stored, reduced, selectively dropped, etc.
  - Through loops, or persisting processors, the stream graph can have state. This allows for dataflow change to be part of the dataflow, and it doesn't require global mutable variables. An example use case for this is when you have a flow of discrete data, and you want to detect when an event is different from the last.

##Information sources

- Akka Stream documentation, also served as reactive stream processing guide book.
- MyoPilot paper and source. The paper (and source) presented a very similar application, and documented mechanisms used in it.
- AR Drone's documentation.
- Myo Armband's documentation.

##Third party code/binary used

- NASA's WorldWind library is called from the myoar.Myo.Angles namespace, specifically WorldWind's quaternion class.
- myo-java are the JVM bindings for Myo's Armband.
- YADrone is the low level ARDrone JVM library.
- Akka Stream library is the reactive stream processing toolkit used.
